@memorysmithapp/markdown-renderer 0.7.0 → 0.8.0

package/README.md

@@ -18,7 +18,7 @@ import 'katex/dist/katex.min.css';
 <NoteBody
   markdown={note}                                  // the note as you keep it, frontmatter included
   resolve={(name) => addressOfTheOneNoteNamed(name)} // or null: the link is pending
-  keeps={(name) => notebookKeepsAFile(name)}       // only an embed reaches a file
+  keeps={(name) => notebookKeepsAFile(name)}       // reached by an embed, and by an image with no host: ![](../assets/x.png)
   fileOf={(name) => describe(name)}               // { mimeType, bytes, url, description }: drawn by its type, as MemorySmith does
   renderLink={({ href, className, children }) => <a href={href} className={className} onClick={follow(href)}>{children}</a>} // follow: your router's navigate, captured where it is
   loadNote={(name) => fetchTheBodyOf(name)}        // for an embedded note; the package never fetches

package/dist/Markdown.d.ts

@@ -1,4 +1,4 @@
-import { type AnchorHTMLAttributes, type ReactNode } from 'react';
+import { type AnchorHTMLAttributes, type ImgHTMLAttributes, type ReactNode } from 'react';
 import { type FootnoteRef } from './footnotes.js';
 import type { TaskSave } from './task-saves.js';
 /**
@@ -40,6 +40,17 @@ export interface MarkdownProps {
 type WithNode<T> = T & {
     node?: unknown;
 };
+/**
+ * An image, with the dimensions the specification puts in its alt text
+ * (§3.14). What precedes the pipe is the description and is never dropped;
+ * what follows it is width, or width and height, in CSS pixels, or a width as
+ * a share of the page at most (#108), and never appears as text. A value that is neither stays part of the description,
+ * because deleting an accessibility label is the worse failure.
+ *
+ * A destination that names no host is a file the notebook keeps, by the last segment of its path
+ * (§5.8, #104): it is drawn as the embed of that file is, and never asked of a path under the page.
+ */
+export declare function MarkdownImage({ alt, node: _node, ...rest }: WithNode<ImgHTMLAttributes<HTMLImageElement>>): import("react").JSX.Element;
 export declare function MarkdownAnchor({ href, children, node: _node, ...rest }: WithNode<AnchorHTMLAttributes<HTMLAnchorElement>>): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
 export declare function Markdown({ children, source, onToggleTask, taskSave, writable, footnotes }: MarkdownProps): import("react").JSX.Element;
 export {};

package/dist/Markdown.js

@@ -7,9 +7,10 @@ import rehypeKatex from 'rehype-katex';
 import { followable } from './address.js';
 import { CopyButton } from './CopyButton.js';
 import { fileAddress, fileKind, formatBytes, opensInBrowser, rendersAs } from './file-types.js';
+import { keptImageName } from './kept-image.js';
 import { highlightLanguage, highlightTree, languageToLoad, loadGrammar } from './highlight.js';
 import { useHost } from './host.js';
-import { readDimensions, readImageAlt } from './image-dimensions.js';
+import { readDimensions, readImageAlt, sizedAttributes } from './image-dimensions.js';
 import { choiceTargetOf, LinkChoice } from './LinkChoice.js';
 import { toUnixNewlines } from './markdown.js';
 import { MermaidDiagram } from './MermaidDiagram.js';
@@ -20,13 +21,21 @@ import { ordinalAt } from './tasklist.js';
 /**
  * An image, with the dimensions the specification puts in its alt text
  * (§3.14). What precedes the pipe is the description and is never dropped;
- * what follows it is width, or width and height, in CSS pixels, and never
- * appears as text. A value that is neither stays part of the description,
+ * what follows it is width, or width and height, in CSS pixels, or a width as
+ * a share of the page at most (#108), and never appears as text. A value that is neither stays part of the description,
  * because deleting an accessibility label is the worse failure.
+ *
+ * A destination that names no host is a file the notebook keeps, by the last segment of its path
+ * (§5.8, #104): it is drawn as the embed of that file is, and never asked of a path under the page.
  */
-function MarkdownImage({ alt, node: _node, ...rest }) {
+export function MarkdownImage({ alt, node: _node, ...rest }) {
     const read = readImageAlt(alt ?? '');
-    return (_jsx("img", { ...rest, alt: read.description, ...(read.width === null ? {} : { width: read.width }), ...(read.height === null ? {} : { height: read.height }) }));
+    const name = typeof rest.src === 'string' ? keptImageName(rest.src) : null;
+    if (name !== null)
+        return _jsx(Attachment, { name: name, size: read, description: read.description, title: rest.title });
+    // The description is the hover hint too, so a person who sees the picture can read it (#109); a title written wins.
+    const title = rest.title || read.description || undefined;
+    return _jsx("img", { ...rest, alt: read.description, title: title, ...sizedAttributes(read) });
 }
 /**
  * A link to a place in the same note: a footnote and its way back (§7.12),
@@ -56,26 +65,19 @@ function InPageAnchor({ href, children, ...rest }) {
     };
     return (_jsx("a", { href: href, onClick: follow, ...rest, children: children }));
 }
-/**
- * A file the notebook keeps, where a note embedded it, drawn by its type — an
- * image, audio, video, or a card — by the host's `renderAttachment`, else from
- * what its `fileOf` says (#77). A name the notebook keeps nothing under is
- * reported the way a pending link is: a notebook is read most while it is
- * being written (§5.8).
- */
-function Attachment({ name, width, height }) {
+function Attachment({ name, size, ...written }) {
     const host = useHost();
     if (!host.keeps(name))
-        return _jsx(AttachmentMissing, { name: name });
+        return _jsx(AttachmentMissing, { name: name, label: written.description });
     if (host.renderAttachment)
-        return _jsx(_Fragment, { children: host.renderAttachment({ name, width, height }) });
+        return _jsx(_Fragment, { children: host.renderAttachment({ name, ...size, ...written }) });
     if (!host.fileOf)
-        return _jsx("span", { className: "attachment-loading", children: name });
-    return _jsx(KeptAttachment, { name: name, width: width, height: height });
+        return _jsx("span", { className: "attachment-loading", children: written.description || name });
+    return _jsx(KeptAttachment, { name: name, size: size, ...written });
 }
-function AttachmentMissing({ name }) {
+function AttachmentMissing({ name, label }) {
     const host = useHost();
-    return (_jsx("span", { className: "attachment-missing", title: host.strings.attachmentMissing, children: name }));
+    return (_jsx("span", { className: "attachment-missing", title: host.strings.attachmentMissing, "data-name": label ? name : undefined, children: label || name }));
 }
 function isThenable(value) {
     return typeof value === 'object' && value !== null && typeof value.then === 'function';
@@ -129,30 +131,36 @@ function openInTab(event, url) {
  * included — a card with what it is, its size, and the ways out of the page: Open only for what a
  * browser shows, Download always. A theme may draw it through the `attachment` slot.
  */
-function KeptAttachment({ name, width, height }) {
+function KeptAttachment({ name, size: declared, ...written }) {
     const host = useHost();
     const slot = useSlot('attachment');
     const described = useKeptFile(name);
     if (described === undefined)
-        return _jsx("span", { className: "attachment-loading", children: name });
+        return _jsx("span", { className: "attachment-loading", children: written.description || name });
     const url = described ? fileAddress(described.url) : '';
     if (!described || url === '')
-        return _jsx(AttachmentMissing, { name: name });
-    const file = { ...described, url, downloadUrl: fileAddress(described.downloadUrl ?? described.url) || url };
+        return _jsx(AttachmentMissing, { name: name, label: written.description });
+    // What the note wrote of the file is what the reader gets of it; the file's own when it wrote nothing.
+    const description = written.description || described.description;
+    const file = {
+        ...described,
+        url,
+        downloadUrl: fileAddress(described.downloadUrl ?? described.url) || url,
+        ...(description ? { description } : {}),
+    };
     const shape = rendersAs(file.mimeType);
     const kind = fileKind(file.mimeType, host.strings.fileKinds);
     const size = formatBytes(file.bytes, host.strings.locale);
     const opens = opensInBrowser(file.mimeType);
     if (slot)
-        return _jsx(_Fragment, { children: drawSlot(slot, { name, file, shape, kind, size, opens, width, height }) });
-    // The attributes reserve the box before the bytes arrive; a height is a style too, since the
-    // surface gives an image `height: auto`, which two numbers overrule (§3.14).
-    const sized = {
-        ...(width === null ? {} : { width }),
-        ...(height === null ? {} : { height, style: { height: `${height}px` } }),
-    };
-    if (shape === 'image')
-        return _jsx("img", { className: "attachment-image", src: file.url, alt: file.description || name, ...sized });
+        return _jsx(_Fragment, { children: drawSlot(slot, { name, file, shape, kind, size, opens, ...declared, title: written.title ?? null }) });
+    const sized = sizedAttributes(declared);
+    if (shape === 'image') {
+        // Described, its description is also the hover hint, a title written winning (#109); a picture
+        // with none takes its name as its `alt` and no hint, which would only say the name again.
+        const title = written.title || file.description;
+        return _jsx("img", { className: "attachment-image", src: file.url, alt: file.description || name, ...(title ? { title } : {}), ...sized });
+    }
     if (shape === 'audio')
         return _jsx("audio", { className: "attachment-player", controls: true, src: file.url });
     if (shape === 'video')
@@ -178,7 +186,7 @@ export function MarkdownAnchor({ href, children, node: _node, ...rest }) {
         const at = address.lastIndexOf('|');
         const measured = at === -1 ? null : readDimensions(address.slice(at + 1));
         const name = measured ? address.slice(0, at) : address;
-        return _jsx(Attachment, { name: name, width: measured?.width ?? null, height: measured?.height ?? null });
+        return _jsx(Attachment, { name: name, size: measured ?? { width: null, height: null, percent: null } });
     }
     if (href?.startsWith('pending:')) {
         const pending = (label) => (_jsx("span", { className: "wikilink-pending", title: host.strings.pendingLink, children: label }));

package/dist/diagnose.js

@@ -11,6 +11,7 @@
  * note, or beside an editor. KaTeX checks a formula as `rehype-katex` would typeset it, and Mermaid
  * reads a diagram as the page would draw it, loaded only when a note carries one.
  */
+import { keptImageName } from './kept-image.js';
 import katex from 'katex';
 import remarkParse from 'remark-parse';
 import { unified } from 'unified';
@@ -36,7 +37,7 @@ export const NOTICES = {
     'raw-html': { severity: 'notice', section: '7.9', message: 'Raw HTML is drawn as text, tags and all.' },
     'strikethrough-single-tilde': { severity: 'notice', section: '4.3', message: 'One tilde strikes nothing: the tildes stay on the page. Strikethrough is ~~two~~.' },
     'link-pending': { severity: 'hint', section: '7.4', message: 'No note answers this link yet, so it is drawn as pending.' },
-    'embed-pending': { severity: 'hint', section: '7.3', message: 'No note and no kept file answers this embed, so it is drawn as a pending link.' },
+    'embed-pending': { severity: 'hint', section: '7.3', message: 'No note and no kept file answers this embed, or no kept file this image, so it is drawn as pending.' },
 };
 /** A footnote reference left as text, which is one with no definition (§7.12). */
 const UNDEFINED_REFERENCE = /\[\^[^\]\s]+\]/g;
@@ -106,6 +107,7 @@ export async function diagnose(markdown, options = {}) {
     const diagrams = [];
     const referenced = new Set();
     const definitions = [];
+    const images = [];
     walk(tree, (node) => {
         const at = span(node);
         if (!at)
@@ -136,6 +138,11 @@ export async function diagnose(markdown, options = {}) {
         else if (node.type === 'footnoteDefinition') {
             definitions.push(node);
         }
+        else if (node.type === 'image') {
+            const name = keptImageName(node.url ?? '');
+            if (name !== null)
+                images.push({ name, at });
+        }
     });
     for (const definition of definitions) {
         const at = span(definition);
@@ -164,6 +171,13 @@ export async function diagnose(markdown, options = {}) {
         }
     });
     pending(hidden, split, options, report);
+    // An image whose destination names no host names a kept file, and only a kept file (§5.8, #104).
+    if (options.resolve || options.reaches) {
+        const keeps = options.keeps ?? (() => false);
+        for (const image of images)
+            if (!keeps(image.name))
+                report('embed-pending', image.at[0], image.at[1], image.name);
+    }
     if (diagrams.length > 0 && options.diagrams !== false) {
         const mermaid = (await import('mermaid')).default;
         for (const diagram of diagrams) {

package/dist/edit/ContextMenu.d.ts

@@ -1,6 +1,6 @@
 /**
  * The editor's own menu on a right-click in edit mode (#81): what the toolbar formats and inserts,
- * where the author is, with the clipboard's three verbs. It is a `role="menu"` reached by keyboard,
+ * where the author is, after the clipboard's three verbs. It is a `role="menu"` reached by keyboard,
  * kept inside the window, and closed by Escape, a click outside it, a scroll, or an entry run.
  */
 import { type ReactNode } from 'react';

package/dist/edit/ContextMenu.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * The editor's own menu on a right-click in edit mode (#81): what the toolbar formats and inserts,
- * where the author is, with the clipboard's three verbs. It is a `role="menu"` reached by keyboard,
+ * where the author is, after the clipboard's three verbs. It is a `role="menu"` reached by keyboard,
  * kept inside the window, and closed by Escape, a click outside it, a scroll, or an entry run.
  */
 import { useEffect, useLayoutEffect, useRef, useState } from 'react';

package/dist/edit/NoteEditor.js

@@ -115,6 +115,8 @@ function insertBlockCommand(name) {
 const NOT_ATTACHING = { state: 'idle', message: null, fraction: null, queued: 0 };
 /** How long the attach button says a file was not attached, when the host did not say why, in milliseconds. */
 const ATTACH_FAILED_MS = 3000;
+/** The keys that write besides a character's own: a note held for the author's choice asks again on them (#101). */
+const WRITING_KEYS = new Set(['Enter', 'Backspace', 'Delete', 'Tab']);
 /** A host's fraction, kept between 0 and 1, or none when it gave no number. */
 function fractionOf(report) {
     const fraction = report?.fraction;
@@ -144,25 +146,21 @@ function Toolbar({ view, host, end, opened, onAttach, attaching, attachButton, }
  * each state, in a slot of one size, so the toolbar never moves as the author types; its word is
  * its title. A failed save's icon is the button that tries again (#66). When the host said why —
  * an alert on a save that succeeded, or the reason for one it refused — the icon is the button that
- * opens what it said, with the host's title as its tooltip, and the author's choices (#86). Whoever
- * hears the page is told the whole of it, why the note stays in edit included.
+ * opens what it said, with the host's title as its tooltip, and the author's choices (#86); a notice
+ * with choices opens by itself as it arrives, and a refusal with choices holds the note until the
+ * author chooses (#101). Whoever hears the page is told the whole of it, why the note stays in edit
+ * included.
  */
-function SaveStatus({ saves, blocked, host, onDecided }) {
+function SaveStatus({ saves, blocked, deciding, open, setOpen, host, onDecided, }) {
     const { state, notice } = saves;
     const words = host.strings.editor;
-    const [open, setOpen] = useState(false);
     const button = useRef(null);
-    // A notice the save no longer carries has nothing left to show.
-    useEffect(() => {
-        if (!notice)
-            setOpen(false);
-    }, [notice]);
     const base = state === 'saving' ? words.saving : state === 'saved' ? host.strings.saved : state === 'failed' ? host.strings.notSaved : '';
-    const shown = notice ? notice.title : base;
-    const said = state === 'failed' && blocked ? (notice ? `${words.stayInEdit}. ${notice.title}` : words.stayInEdit) : shown;
+    const shown = notice ? (deciding ? `${notice.title}. ${words.chooseToEdit}` : notice.title) : base;
+    const said = state === 'failed' && blocked ? (notice ? `${words.stayInEdit}. ${shown}` : words.stayInEdit) : shown;
     const icon = state === 'saving' ? ICONS.saving : state === 'saved' ? ICONS.saved : state === 'alert' ? ICONS.alert : state === 'failed' ? ICONS.notSaved : null;
     const retryLabel = `${said}. ${words.retry}`;
-    return (_jsxs("div", { className: "edit-save", "data-save": state, title: state === 'failed' || notice ? undefined : said || undefined, children: [notice ? (_jsx("button", { ref: button, type: "button", className: "edit-save-icon edit-save-notice", title: notice.title, "aria-label": notice.title, "aria-haspopup": "dialog", onClick: () => setOpen(true), children: icon })) : state === 'failed' ? (_jsx("button", { type: "button", className: "edit-save-icon edit-save-retry", title: retryLabel, "aria-label": retryLabel, onClick: saves.retry, children: icon })) : (_jsx("span", { className: "edit-save-icon", children: icon })), _jsx("span", { className: "visually-hidden", role: "status", "aria-live": "polite", children: said }), open && notice && (_jsx(SaveNoticeDialog, { notice: notice, onClose: () => setOpen(false), onClosed: (chosen) => (chosen ? onDecided() : button.current?.focus()), onAction: (action) => {
+    return (_jsxs("div", { className: "edit-save", "data-save": state, title: state === 'failed' || notice ? undefined : said || undefined, children: [notice ? (_jsx("button", { ref: button, type: "button", className: "edit-save-icon edit-save-notice", title: shown, "aria-label": shown, "aria-haspopup": "dialog", onClick: () => setOpen(true), children: icon })) : state === 'failed' ? (_jsx("button", { type: "button", className: "edit-save-icon edit-save-retry", title: retryLabel, "aria-label": retryLabel, onClick: saves.retry, children: icon })) : (_jsx("span", { className: "edit-save-icon", children: icon })), _jsx("span", { className: "visually-hidden", role: "status", "aria-live": "polite", children: said }), open && notice && (_jsx(SaveNoticeDialog, { notice: notice, onClose: () => setOpen(false), onClosed: (chosen) => (chosen ? onDecided() : button.current?.focus()), onAction: (action) => {
                     setOpen(false);
                     saves.run(action);
                 } }))] }));
@@ -181,8 +179,18 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
     const environment = useRef(new Compartment());
     const access = useRef(new Compartment());
     const saves = useEditSaves(onChange);
-    const latest = useRef({ hand: saves.hand, host: resolved, onLeave });
-    latest.current = { hand: saves.hand, host: resolved, onLeave };
+    /**
+     * A refusal that gives the author choices — another person wrote the note, say — is decided
+     * before the note is written in again: every save after it would be refused too (#101).
+     */
+    const deciding = saves.state === 'failed' && (saves.notice?.actions.length ?? 0) > 0;
+    const [noticeOpen, setNoticeOpen] = useState(false);
+    // A notice with choices opens by itself as it arrives; one the save no longer carries closes.
+    useEffect(() => {
+        setNoticeOpen(!!saves.notice && saves.notice.actions.length > 0);
+    }, [saves.notice]);
+    const latest = useRef({ hand: saves.hand, host: resolved, onLeave, deciding, ask: () => setNoticeOpen(true) });
+    latest.current = { hand: saves.hand, host: resolved, onLeave, deciding, ask: () => setNoticeOpen(true) };
     /**
      * The texts handed to the host that it has not given back yet. A host that saves before it
      * passes the note again gives back a text the editor has since moved past; that echo is not a
@@ -253,7 +261,7 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
     /** Where the editing menu is open, in the window's coordinates (#81). */
     const [menu, setMenu] = useState(null);
     const openMenu = useRef((x, y) => setMenu({ x, y }));
-    /** The menu's groups, from the same commands as the toolbar: Format with a selection, Insert, Edit. */
+    /** The menu's groups, from the same commands as the toolbar: Edit first (#110), Format with a selection, Insert. */
     const menuGroups = (target) => {
         const words = resolved.strings.editor;
         const item = (name, action, shortcut) => ({
@@ -300,7 +308,8 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
                 { name: 'attach', label: words.attach, icon: ICONS.attach, run: () => setAttachOpen(true) },
             ],
         });
-        groups.push({
+        // The clipboard's verbs open the menu, as they open every other one a person knows (#110).
+        groups.unshift({
             label: words.menuEdit,
             items: [
                 {
@@ -336,7 +345,9 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
     // The note as edit mode opened it, as the editor holds its text: lines joined by `\n`.
     const opened = useRef(given.replace(/\r\n?/g, '\n'));
     const lineBreak = lineBreakOf(given);
-    const readOnly = !editable || lineBreak === null;
+    const locked = !editable || lineBreak === null;
+    // Held while the author decides: the caret still moves, and a key that would write asks again.
+    const readOnly = locked || deciding;
     /**
      * The editor splits its text on any line break, so a paste or a block written with `\n` is lines
      * like any other, and writes the note back with the break it was written with: what a host
@@ -353,7 +364,7 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
             state: EditorState.create({
                 doc: given,
                 extensions: [
-                    access.current.of([EditorState.readOnly.of(readOnly), EditorView.editable.of(!readOnly)]),
+                    access.current.of([EditorState.readOnly.of(readOnly), EditorView.editable.of(!locked)]),
                     environment.current.of(editorEnvironment.of({ host: resolved })),
                     history(),
                     markdown(),
@@ -373,6 +384,16 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
                         return true;
                     }),
                     EditorView.domEventHandlers({
+                        // A key that would write, while the note waits for the author's choice, shows the choice again (#101).
+                        keydown: (event) => {
+                            if (!latest.current.deciding || event.ctrlKey || event.metaKey || event.altKey)
+                                return false;
+                            if (event.key.length !== 1 && !WRITING_KEYS.has(event.key))
+                                return false;
+                            event.preventDefault();
+                            latest.current.ask();
+                            return true;
+                        },
                         // The editing menu where the pointer is; Shift keeps the browser's, and so do the
                         // drawn blocks' own fields, which are the browser's to edit (#81).
                         contextmenu: (event, target) => {
@@ -436,8 +457,8 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
         view?.dispatch({ effects: environment.current.reconfigure(editorEnvironment.of({ host: resolved })) });
     }, [view, resolved]);
     useEffect(() => {
-        view?.dispatch({ effects: access.current.reconfigure([EditorState.readOnly.of(readOnly), EditorView.editable.of(!readOnly)]) });
-    }, [view, readOnly]);
+        view?.dispatch({ effects: access.current.reconfigure([EditorState.readOnly.of(readOnly), EditorView.editable.of(!locked)]) });
+    }, [view, readOnly, locked]);
     // A note the host changed — a tick saved, another device — is taken in as the change it is.
     useEffect(() => {
         if (!view)
@@ -513,7 +534,7 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
                             else
                                 setRefusal(null);
                             setAttachOpen(true);
-                        }, attaching: attaching, attachButton: attachButton, end: _jsxs("div", { className: "edit-corner", "aria-busy": leaving && saves.state === 'saving' ? true : undefined, "data-blocked": blocked ? '' : undefined, children: [_jsx(SaveStatus, { saves: saves, blocked: blocked, host: resolved, onDecided: () => view?.focus() }), corner ?? _jsx(NoteActions, { display: buttons, text: () => (view ? output(view.state) : given) })] }, blocked ? `blocked-${refusals}` : 'corner') }) }), menu && view && (_jsx(ContextMenu, { x: menu.x, y: menu.y, label: resolved.strings.editor.menu, groups: menuGroups(view), onClose: (back) => {
+                        }, attaching: attaching, attachButton: attachButton, end: _jsxs("div", { className: "edit-corner", "aria-busy": leaving && saves.state === 'saving' ? true : undefined, "data-blocked": blocked ? '' : undefined, children: [_jsx(SaveStatus, { saves: saves, blocked: blocked, deciding: deciding, open: noticeOpen, setOpen: setNoticeOpen, host: resolved, onDecided: () => view?.focus() }), corner ?? _jsx(NoteActions, { display: buttons, text: () => (view ? output(view.state) : given) })] }, blocked ? `blocked-${refusals}` : 'corner') }) }), menu && view && (_jsx(ContextMenu, { x: menu.x, y: menu.y, label: resolved.strings.editor.menu, groups: menuGroups(view), onClose: (back) => {
                         setMenu(null);
                         if (back)
                             view.focus();

package/dist/edit/blocks.d.ts

@@ -29,12 +29,28 @@ export declare function CalloutBlock({ view, text, marker }: {
         fold: '+' | '-' | null;
     };
 }): import("react").JSX.Element;
+/** The narrowest an image is sized to, by a field or the handle: something a reader still sees (#105). */
+export declare const MIN_IMAGE_SIZE = 16;
 /**
- * An image drawn in edit mode with the size it is drawn at set in place (#98): a width in pixels,
- * its height following, a handle at its corner that drags it, and a button back to its own size.
- * Each writes the dimensions of its notation — `![description|300](…)` or `![[photo.jpg|300]]` —
- * and no other byte. The controls appear once an image is drawn inside it, so an embed of a file
- * that is not an image, or a host's own drawing without one, offers none.
+ * An image drawn in edit mode with what its notation writes set in place (#98, #106): its width and
+ * its height with a lock between them — locked, the height follows and only the width is written,
+ * `|300`; open, both are, `|300x180` — the width's unit, pixels or a share of the page (`|50%`,
+ * #108), its description for a Markdown image, a button back to its own size, and a handle at its
+ * corner that drags it, keeping the proportion or, with the lock open or Shift held, not. Each
+ * writes the dimensions or the description of its notation, and no other byte.
+ *
+ * A field selects what it holds when it takes the focus, so typing replaces it, and writes on Enter
+ * or when it is left; Escape leaves the note as it is. A value outside the range a reader can see
+ * — from 16 pixels to the column or the image's own width, the wider — is refused where it was
+ * typed, never brought into the range and written (#105).
+ *
+ * The controls stand under the picture, never over it, and nothing that starts on them or in the
+ * moment after reaches the click that shows the image's source (#107): they are all marked as
+ * controls, gaps included, and the frame is marked busy while one of them has the focus, while the
+ * handle is dragged and for a moment after a pointer or a touch on them.
+ *
+ * The controls appear once an image is drawn inside it, so an embed of a file that is not an image,
+ * or a host's own drawing without one, offers none.
  */
 export declare function ImageBlock({ view, source, children }: {
     view: EditorView;